Add guidance for .NET library dependency versions #49958
Conversation
Added guidance for selecting .NET library dependency versions, including strategies, tradeoffs, and recommendations for library authors.
ericstj
requested review from
DamianEdwards,
ViktorHofer,
eerhardt,
gewarren,
jeffhandley,
joperezr,
richlander and
stephentoub
There was a problem hiding this comment.
Pull Request Overview
This PR introduces comprehensive guidance for .NET library authors on selecting dependency versions when targeting multiple .NET framework versions. The document outlines three primary strategies (latest supported versions, TFM-specific versions, and branching), their tradeoffs, and provides concrete recommendations with code examples.
Key changes:
- New guidance document explaining dependency version selection strategies for .NET libraries.
- Decision matrix comparing engineering, servicing, and update friction costs across strategies.
- Code examples demonstrating each approach using System.Text.Json references.
Show contrast to framework overlapping package and not.
Co-authored-by: Stephen Toub <[email protected]>
|
I've addressed all feedback, please have another pass at this. Thank you. |
There was a problem hiding this comment.
You'll need to add this to the TOC somewhere. Maybe below this article in this file?
| @@ -0,0 +1,171 @@ | |||
| --- | |||
| ai-usage: ai-assisted | |||
There was a problem hiding this comment.
| ai-usage: ai-assisted | |
| title: Guidance for .NET library dependency versions | |
| description: Learn about the strategies and recommendations for choosing dependency versions when you build a library that targets multiple .NET versions. | |
| ms.date: 11/24/2025 | |
| ai-usage: ai-assisted |
| When building libraries that target multiple .NET versions, choosing dependency versions has implications for compatibility, servicing, and ecosystem health. This document outlines the main strategies, their tradeoffs, and recommendations. | ||
|
|
||
| --- |
There was a problem hiding this comment.
| When building libraries that target multiple .NET versions, choosing dependency versions has implications for compatibility, servicing, and ecosystem health. This document outlines the main strategies, their tradeoffs, and recommendations. | |
| --- | |
| When you build libraries that target multiple .NET versions, choosing dependency versions has implications for compatibility, servicing, and ecosystem health. This article outlines the main strategies, their tradeoffs, and recommendations. |
|
|
||
| --- | ||
|
|
||
| ## **Overview** |
There was a problem hiding this comment.
| ## **Overview** | |
| ## Overview |
|
|
||
| ## **Overview** | ||
|
|
||
| Library authors face challenges when deciding which version of a .NET dependency to reference. Newer versions have more API and features, but may require a local redistribution increasing servicing responsibilities of the library and size of the application. The decision impacts: |
There was a problem hiding this comment.
| Library authors face challenges when deciding which version of a .NET dependency to reference. Newer versions have more API and features, but may require a local redistribution increasing servicing responsibilities of the library and size of the application. The decision impacts: | |
| Library authors face challenges when deciding which version of a .NET dependency to reference. Newer versions have more APIs and features but might require a local redistribution, which increases servicing responsibilities of the library and size of the application. The decision impacts: |
| ## **Examples** | ||
|
|
||
| ### Example 1: Latest supported version | ||
| ```xml |
There was a problem hiding this comment.
| ```xml | |
| ```xml |
| ``` | ||
|
|
||
| ### Example 2: TFM-specific versions | ||
| ```xml |
There was a problem hiding this comment.
| ```xml | |
| ```xml |
| ``` | ||
|
|
||
| ### Example 3: Branching | ||
| Branch: release/8.0 |
There was a problem hiding this comment.
| Branch: release/8.0 | |
| Branch: release/8.0 | |
| </ItemGroup> | ||
| ``` | ||
|
|
||
| Branch: release/9.0 |
There was a problem hiding this comment.
| Branch: release/9.0 | |
| Branch: release/9.0 | |
| </ItemGroup> | ||
| ``` | ||
|
|
||
| Branch: release/10.0 |
There was a problem hiding this comment.
| Branch: release/10.0 | |
| Branch: release/10.0 | |
| <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks> | ||
| </PropertyGroup> | ||
| <ItemGroup> | ||
| <PackageReference Condition="'$(TargetFramework)' == 'net8.0'" Include="System.IO.Packaging" Version="8.0.0" /> |
There was a problem hiding this comment.
Sorry I wasn't clear earlier about the example.
I think a good example here would be Microsoft.Extensions.Logging.Abstractions. It isn't in the shared framework, but lifts a dependency on a library that is in the shared framework.
https://www.nuget.org/packages/Microsoft.Extensions.Logging.Abstractions/#dependencies-body-tab
If a library references the 10.0.0 version of Microsoft.Extensions.Logging.Abstractions, System.Diagnostics.DiagnosticSource will be lifted out of the shared framework for all net8 and net9 apps that reference the library.
This is first draft. I might be assuming too much familiarity with the problem space. Please provide feedback 🤝
Internal previews